HYPERMAIL

NAME

SYNOPSIS

DESCRIPTION

Each HTML file that is generated for a message contains (where applicable): the subject of the article, the name and email address of the sender, the date the article was sent, links to the next and previous messages in the archive, a link to the message the article is in reply to, and a link to the message next in the current thread.

In addition, Hypermail will convert references in each message to email addresses and URLs to hyperlinks so they can be selected. Email addresses will be converted to mailto: URLs. or links to a CGI mail program. Note that not all World-Wide Web browsers support the mailto: URL yet.

To complement each set of HTML messages, four index files are created which sort the articles by date received, thread, subject, and author. Each entry in these index files are links to the individual articles and provide a bird's-eye view of every archived message:

date.html

The index of articles sorted by the date they were received by the mail daemon.

thread.html

The index of articles sorted by thread first, then the date they were received.

subject.html

The index of articles sorted by subject. Any Re: prefixes in front of subjects will have been stripped out.

author.html

is the index of articles sorted by the first word of the author's name. If the author's name can't be determined, their email address will be substituted.

One of the index files will be called index.html and is the default index that users can go to when entering the archive. In the specified directory, articles will be read out in the order that they were read from a mailbox or standard input. Filenames start at zero and increase in this fashion: 0000.html, 0001.html, 0002.html, etc.  

OPTIONS

-i

Reads in articles from standard input.

-m mailbox

Specifies the mailbox to read articles in from. By default, Hypermail will look for a file called mbox. Note that the -i and -m options cannot be used together. Only archives in UNIX mailbox format can be read in - mailboxes of this kind are usually appended RFC 822-compliant articles separated by lines such as "\nFrom person@site Mon Jan 10 12:34:56 1994".

-d directory

Specifies the directory to put the HTML files and index files that are created. If the directory doesn't exist, a new one will be created with the name that is specified. If the -d option isn't used, Hypermail will look for a directory with the same name as the input mailbox or will create one if needed.

-l label

This option tells Hypermail what to call the archive - the name that is specified will be in the title of the index pages so users know what sort of messages are being archived.

-a URL

This option includes a link labelled Other mail archives in the index pages to the specified URL. This way users who are looking at the Hypermail archive have the opportunity to go to pointers to other mail archives. By default, this is a link to the parent directory which holds the archive files.

-b URL

This option includes a link labelled About this archive in the index pages to the specified URL. This way users who are looking at the Hypermail archive have the opportunity to go to information about the archive.

-c file

This option specifies a configuration file to read settings from. By default, Hypermail will look for a file called .hmrc in the user's home directory.

-x

This tells Hypermail to explicitly overwrite any previous HTML files that may exist. Use this option only when it is desirable to completely rewrite the entire archive.

-u

This updates archives by one message only. With this option, only one email message will be read in from a file or standard input. This message will be added to the end of the existing HTML file archive and will be integrated into it by links and cross-references. All archive index files will be regenerated to include the new message.

-p

This shows a progress report as Hypermail reads in and writes out messages - the number of files that Hypermail is reading and writing and the file names of the directory and files created are shown.

If the -u option is used and articles are read in from a mailbox file, Hypermail will assume that the file contains only one article, no matter how many files the mailbox may actually contain. Make sure that Hypermail is given only one article when using this option.

If the mailbox that is being read from is an archive that new messages are always being added to, don't use the -u or -x options. Hypermail will then read in all the messages given it but will only write new messages that have been appended to the mailbox.

Note that no matter what options are specified, the index files are always rewritten. The date when Hypermail was last run is included in index pages, so it's easy to tell when the archive was last updated.  

CONFIGURATION OPTIONS

The following settings can be read in as environment variables or from the specified configuration file. Environment settings are in uppercase. For instance, in the C shell, variables can be set as:

setenv HM_MBOX /home/john/my_mailbox

setenv HM_FILEMODE 0600

In the configuration file, blank lines and lines beginning with a hash mark (#) are ignored. Variables must be in lowercase and separated by values with an equals (=) sign, such as:

set hm_mbox = /home/john/my_mailbox

set hm_filemode = 0600

Settings are read in this order: from the program's hard-wired internal defaults, from environment variables, from command-line options, from the configuration file.

Below is a list of variables that Hypermail understands. Boolean numbers can have the value of 0 or 1.

HM_CONFIGFILE filename

This is the default configuration file to read settings in from. This can only be specified as an environment variable. If the first character is "~", Hypermail will look for the file under the current user's home directory.

HM_MBOX filename

This is the default mailbox to read messages in from. Define this with a value of NONE to read from standard input as the default.

HM_ARCHIVES URL

This will create a link in the archived index pages labelled Other mail archives to the specified URL. Define as NONE to omit such a link.

HM_ABOUT URL

This will create a link in the archived index pages labelled About this archive to the specified URL. Define as NONE to omit such a link.

HM_REVERSE boolean_number

Defining this variable as 1 will reverse-sort the article entries in the date and thread index files by the date they were received. That is, the most recent messages will appear at the top of the index rather than the other way around.

HM_SHOWHEADERS boolean_number

Define this as 1 to show the article header lines in the archived HTML files. These lines typically include the To:, From:, and Subject: information found in most email messages.

HM_SHOWHTML boolean_number

Define as 1 this to show the articles in a proportionally-spaced font rather than a fixed-width (monospace) font. Defining this option will also tell Hypermail to attempt to italicize quoted passages in articles.

HM_LABEL label name

Define this as the default label to put in archives.

HM_DIR directory

This is the default directory that Hypermail will look for when creating and updating archives. If defined as NONE the directory will have the same name as the input mailbox.

HM_DIRMODE octal_number

This is an octal number that new directories are set to when they are created. If the archives will be made publically available, it's a good idea to define this as 0755. If files will be updated incrementally with sendmail, this will have to be 0777.

HM_FILEMODE octal_number

This is an octal number that new files are set to when they are created. If the archives will be made publically available, it's a good idea to define this as 0644. If files will be updated incrementally with sendmail, this will have to be 0666.

HM_OVERWRITE boolean_number

Define as 1 to make Hypermail overwrite existing archives by default.

HM_INCREMENT boolean_number

Define as 1 to read one article only and append it to existing archives by default.

HM_PROGRESS boolean_number

Define as 1 to always show a progress report as Hypermail works.

HM_THRDLEVELS number

This specifies the number of thread levels to outline in the thread index. For instance, if THRDLEVELS is 2, replies to messages will be indented once in the index, but replies to replies, etc., will only be indented once as well.

HM_DEFAULTINDEX type

This specifies the default index that users can view when entering the archive. Valid types are date, thread, author, and subject.

BUGS

Sorting: In the date and thread index files, note that these lists are sorted by the date the articles were received by the system's mail daemon, not by the date they were written on. The order of articles in the date index may not necessarily match the order in which the article files are written and linked together. Because of this, it is a good idea to make sure the mailbox is sorted by date with the most recent messages towards the bottom.

RFC 822-compliant headers on multiple lines aren't recognized.

Forwarded messages with bad headers may be incorrectly handled.

The URL and email hyperlink parser can only handle one instance of both per line.  

AUTHORS

Hypermail was originally developed and designed by Tom Gruber (gruber@ksl.stanford.edu) for Enterprise Integration Technologies (EIT) in Common Lisp. It was later rewritten in C by Kevin Hughes (kevinh@eit.com) at EIT.

http://www.eit.com/software/hypermail/hypermail.html

The latest documentation can be found at this World-Wide Web address.

http://gummo.stanford.edu/html/hypermail/hypermail.html

Documentation for the Common Lisp version of Hypermail can be found at this address.

Note that Hypermail is subject to license restrictions. It may be freely used for noncommercial purposes. Unauthorized commercial distribution is prohibited.

Index

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

CONFIGURATION OPTIONS

BUGS

AUTHORS